# -*- coding: utf-8 -*-
"""
Swagger API文档配置

功能说明:
- 定义Swagger API文档的基本信息
- 配置API文档的显示样式和行为
- 提供统一的API文档管理

作者: MetasoCreator Team
创建时间: 2025-01-19
修改时间: 2025-01-19
"""

from flask_restx import Api
from flask import Blueprint


# Swagger API文档配置
SWAGGER_CONFIG = {
    'title': 'MetasoCreator API',
    'version': '1.0.0',
    'description': '''
    MetasoCreator智能创作系统API文档
    
    ## 功能模块
    
    ### 搜索模块 (Search)
    - 网页搜索：基于秘塔AI的智能搜索功能
    - 搜索建议：提供搜索关键词建议
    - 搜索历史：管理用户搜索记录
    
    ### 内容管理模块 (Content)
    - 内容创建：创建新的内容项目
    - 内容编辑：编辑和更新内容
    - 内容导出：支持多种格式导出
    - 内容列表：查看和管理所有内容
    
    ### 系统模块 (System)
    - 健康检查：系统状态监控
    - API信息：接口文档和版本信息
    
    ## 认证方式
    目前系统暂未启用认证，所有接口均可直接访问。
    
    ## 错误码说明
    - 200: 请求成功
    - 400: 请求参数错误
    - 404: 资源不存在
    - 500: 服务器内部错误
    
    ## 数据格式
    所有接口均返回JSON格式数据，统一响应格式：
    ```json
    {
        "success": true/false,
        "message": "响应消息",
        "data": {},
        "timestamp": "2025-01-19T10:00:00Z"
    }
    ```
    ''',
    'doc': '/docs/',
    'validate': True,
    'ordered': True,
    'contact': 'MetasoCreator Team',
    'contact_email': 'team@metasocreator.com',
    'license': 'MIT',
    'license_url': 'https://opensource.org/licenses/MIT',
    'terms_url': 'https://metasocreator.com/terms',
    'prefix': '/api',
    'tags': [
        {
            'name': 'search',
            'description': '搜索相关接口'
        },
        {
            'name': 'content',
            'description': '内容管理相关接口'
        },
        {
            'name': 'system',
            'description': '系统相关接口'
        }
    ]
}


# 创建API实例的工厂函数
def create_api(blueprint: Blueprint) -> Api:
    """
    创建Flask-RESTX API实例
    
    Args:
        blueprint: Flask蓝图实例
        
    Returns:
        Api: 配置好的API实例
    """
    api = Api(
        blueprint,
        title=SWAGGER_CONFIG['title'],
        version=SWAGGER_CONFIG['version'],
        description=SWAGGER_CONFIG['description'],
        doc=SWAGGER_CONFIG['doc'],
        validate=SWAGGER_CONFIG['validate'],
        ordered=SWAGGER_CONFIG['ordered'],
        contact=SWAGGER_CONFIG['contact'],
        contact_email=SWAGGER_CONFIG['contact_email'],
        license=SWAGGER_CONFIG['license'],
        license_url=SWAGGER_CONFIG['license_url'],
        terms_url=SWAGGER_CONFIG['terms_url']
    )
    
    # 添加标签
    for tag in SWAGGER_CONFIG['tags']:
        api.add_namespace(
            api.namespace(
                tag['name'],
                description=tag['description'],
                path=f"/{tag['name']}"
            )
        )
    
    return api


# 通用响应模型
COMMON_RESPONSES = {
    200: 'Success',
    400: 'Bad Request - 请求参数错误',
    404: 'Not Found - 资源不存在',
    500: 'Internal Server Error - 服务器内部错误'
}


# API文档主题配置
SWAGGER_UI_CONFIG = {
    'deepLinking': True,
    'displayOperationId': False,
    'defaultModelsExpandDepth': 1,
    'defaultModelExpandDepth': 1,
    'defaultModelRendering': 'example',
    'displayRequestDuration': True,
    'docExpansion': 'none',
    'filter': True,
    'showExtensions': True,
    'showCommonExtensions': True,
    'tryItOutEnabled': True
}